<HTML>
<!--This file created 14/3/01 8:53 AM by Claris Home Page version 3.0-->
<HEAD>
   <TITLE>Batch Architect: Instructions File Format</TITLE>
   <META NAME=GENERATOR CONTENT="Claris Home Page 3.0">
   <X-CLARIS-WINDOW TOP=42 BOTTOM=757 LEFT=4 RIGHT=534>
   <X-CLARIS-TAGVIEW MODE=minimal>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</HEAD>
<BODY bgcolor="#FFFFCC">
<H2> 
  <TABLE BORDER=0 CELLPADDING=4>
   <TR>
      <TD> <P><img src="splash.gif" width="164" height="64"></P>
      </TD>
      <TD> <H2>Batch Architect: Instruction File Format</H2>
      </TD>
   </TR>
</TABLE>
</H2>

<p><a href="index.html">Return to Batch Architect Page</a></p>
<H4>David Maddison &amp; Wayne Maddison</H4>

<P>A Mesquite Instruction File is a text file describing the contents of one or 
  more other text files containing data. The Instruction File gives enough details 
  about the other text files to allow Mesquite to be able to read it. </P>
<h4>Structure of the data file to be read</h4>
<P>The data file that is to be described by the Instructions File must consist 
  of a series of records, each record represented by the same number of elements, 
  and each element must be separated by either a tab or a new line or carriage 
  return. For example, you might have a file with various numbers given for each 
  of a series of five trees. The data for each tree might be on a single line, 
  and there might be three numbers per tree. There would thus be five records 
  (corresponding to the five trees), and each record would have exactly three 
  numbers. </P>
<h4>Instruction File format</h4>
<P>The format of the instruction file is currently very primitive and simple; 
  eventually, it will be altered to use standard languages such as XML, and allow 
  more flexibility, but for the moment it is formatted as follows.</P>
<ol>
  <li> The first line must be &quot;MesquiteInstructions&quot;<br>
  </li>
  <li>The second line gives the number of data elements to be read in and stored 
    for each record. Currently the maximum number of elements to 
    be stored is 12. There can be many more elements per record, but if there 
    are more than the maximum number, some of them will not be able to be stored 
    by Mesquite. The form of this line is<br>
    <br>
    numVariables = &lt;number of elements to be read and stored&gt;<br>
  </li>
  <li>The third line describes how many files are to be read. The current maximum 
    is 2. If more than one file is to be read, the two files need not have the 
    same format.<br>
  </li>
  <li>The next lines specify the layout of each file to be read, using the format:<br>
    <br>
    file1 = 'itemsPerRecord=&lt;number of elements total in each record&gt; v1=&lt;element 
    number of first variable&gt; v2=&lt;element number of second variable&gt;...'<br>
    <br>
    For the second file, use <br>
    <br>
    file2 = ...<br>
  </li>
  <li>An optional line can be included specifying the name to be applied to the 
    records:<br>
    <br>
    recordLabel = &lt;label for records&gt;<br>
  </li>
  <li>An optional line can be included specifying a simple formula to manipulate 
    the data, of the form:<br>
    <br>
    formula = 'v1-v2'<br>
    <br>
    The formula can consist of nothing more than two variables with one of the 
    standard four operators (+, -, *, /).<br>
    <br>
    If a formula is defined, you can label it with<br>
    <br>
    formulaLabel = &lt;label for formula&gt;<br>
  </li>
  <li>Optional lines can then be give naming each of the variables that has been 
    stored:<br>
    <br>
    label1 = &lt;label for variable 1&gt;<br>
    label2 = &lt;label for variable 2&gt;<br>
  </li>
</ol>
<p>For each of these parts of the description, the &lt;specification&gt; part 
  must consist of a single token; thus, if you wish to label something with multiple 
  words, surround them by single quotes, as in 'Gamma Shape'.</p>
<h4>Example</h4>
<P>Imagine that you wished to ask PAUP* to estimate the value of the gamma shape 
  parameter and proportion of invariant characters for a series of trees. The 
  PAUP* commands you might give are:<br>
</P>
<pre>   lset basefreq=empirical nst=1 pinvar=estimate rates=gamma shape=estimate;
   lscoreall/scorefile='score';</pre>
<P>The start of the score file that would be generated would look something like 
  this:</P>
<pre>   Tree -lnL p-inv gamma shape
   1 8430.14114160 0.59050567 1.075992
   2 8410.59386351 0.57306194 0.991805
   3 7922.53719113 0.64386747 1.401232</pre>
<p>The first step would be to strip the first line out of the score file, to yield:</p>
<pre>   1 8430.14114160 0.59050567 1.075992 
   2 8410.59386351 0.57306194 0.991805 
   3 7922.53719113 0.64386747 1.401232</pre>
<p>Each record has four items. If you wished Mesquite to read in only the estimate 
  of the porportion of invariable characters and the gamma shape parameters, then 
  you will want Mesquite to read in the third and fourth item in each record. 
  The MesquiteInstructions file for processing this might then be:</p>
<pre>   MesquiteInstructions
   numVariables = 2
   numFiles = 1
   file1 = 'itemsPerRecord=4 v1=3 v2=4'
   recordLabel = 'Replicates'
   label1 = 'proportion invariable
   label2 = 'gamma shape'</pre>
<p>&nbsp;</p>

<P>

<HR>

</P>

<P>&copy; David Maddison &amp; Wayne Maddison, 2005</P>
</BODY>
</HTML>

